home *** CD-ROM | disk | FTP | other *** search
/ The CICA Windows Explosion! / The CICA Windows Explosion! - Disc 2.iso / programr / wincap.zip / DIBAPI.TXT < prev    next >
Text File  |  1991-11-05  |  12KB  |  279 lines
  1.             DIB Screen Capture/Printing API Specification
  2.                    By Pat Schreiber and Mark Bader
  3.                     Version dated October 8, 1991
  4.     Copyright (c) 1991 Microsoft Corporation. All rights reserved.
  5.  
  6.  
  7. PrintWindow
  8. Syntax    WORD PrintWindow(hWnd, fPrintArea, fPrintOpt,
  9.                     wXScale, wYScale, szJobName)
  10.           
  11.           This function prints an entire window or its client
  12.           area on the current default printer.  Banding is used
  13.           if the printer driver supports it.
  14.           
  15.           Parameter      Type/Description
  16.           hWnd           HWND   Specifies the window to be
  17.                                 printed.
  18.           
  19.           fPrintArea     WORD   Specifies the area(s) of the
  20.                                 window to be printed.  See
  21.                                 below for a listing of the
  22.                                 possible values for this
  23.                                 parameter.
  24.           
  25.           fPrintOpt      WORD   Species the printing options.
  26.                                 See below for a listing of the
  27.                                 possible values for this
  28.                                 parameter.
  29.           
  30.           wXScale        WORD   Specifies the x-axis scaling
  31.                                 factor for the printed window.
  32.                                 The x and y scaling factors
  33.                                 are only used if the PW_SCALE
  34.                                 option below is selected.
  35.           
  36.           wYScale        WORD   Specifies the y-axis scaling
  37.                                 factor.
  38.           
  39.           szJobName      LPSTR  Specifies the name of the print
  40.                                 job.  This string is used in
  41.                                 the job name sent to the print
  42.                                 spooler, as well as in the
  43.                                 print dialog box.
  44.           
  45.           The fPrintArea parameter must be set to one of the
  46.           following:
  47.           
  48.           Value             Meaning
  49.           PW_WINDOW         Print the entire window.
  50.           
  51.           PW_CLIENT         Print the client area of the
  52.                             window.
  53.           
  54.           The fPrintOpt parameter must be set to one of the
  55.           following:
  56.           
  57.           Value             Meaning
  58.           PW_BESTFIT        Fits the printed screen on the page
  59.                             in as large of a area as possible
  60.                             while still retaining the correct
  61.                             screen aspect ratio.  The wXScale
  62.                             and wYScale parameters are not
  63.                             used if this option is selected.
  64.                             This is the default value.
  65.           
  66.           PW_STRETCHTOPAGE  Stretches the printed screen to
  67.                             fill up the entire printed page.
  68.                             The wXScale and wYScale parameters
  69.                             are not used if this option is
  70.                             selected.
  71.           
  72.           PW_SCALE          Scales the printed screen by the
  73.                             integer scaling factors specified
  74.                             in the wXScale and wYScale
  75.                             parameters.   If the scaling is
  76.                             set too large, the screen may
  77.                             extend off the printed page and
  78.                             will be clipped.
  79.           
  80. Return Value   0 if successful, or one of: ERR_DIBFUNCTION,
  81.           ERR_INVALIDHANDLE, ERR_LOCK, ERR_SETABORTPROC,
  82.           ERR_STARTDOC, ERR_NEWFRAME, ERR_ENDDOC, ERR_GETDC,
  83.           ERR_STRETCHDIBITS.  These constants are defined in
  84.           errors.h.
  85.  
  86. PrintScreen
  87. Syntax    WORD PrintScreen(rRegion, fPrintOpt, wXScale,
  88.                     wYScale, szJobName)
  89.           
  90.           This function prints the specified area of the screen
  91.           on the default printer.
  92.           
  93.           Parameter      Type/Description
  94.           rRegion        LPRECT Specifies the region of the
  95.                                 screen (in screen coordinates)
  96.                                 to be printed.  To print the
  97.                                 entire screen, set this rect
  98.                                 to encompass the entire
  99.                                 screen.
  100.           
  101.           fPrintOpt      WORD   Species the printing options.
  102.           
  103.           wXScale        WORD   Specifies the x-axis scaling
  104.                                 factor for the printed window.
  105.                                 The x and y scaling factors
  106.                                 are only used if the PW_SCALE
  107.                                 option below is selected.
  108.           
  109.           wYScale        WORD   Specifies the y-axis scaling
  110.                                 factor.
  111.           
  112.           szJobName      LPSTR  Specifies the name of the print
  113.                                 job.  This string is used in
  114.                                 the job name sent to the print
  115.                                 spooler, as well as in the
  116.                                 print dialog box.
  117.           
  118. Return Value   0 if successful, or one of: ERR_DIBFUNCTION,
  119.           ERR_INVALIDHANDLE, ERR_LOCK, ERR_SETABORTPROC,
  120.           ERR_STARTDOC, ERR_NEWFRAME, ERR_ENDDOC, ERR_GETDC,
  121.           ERR_STRETCHDIBITS.  These constants are defined in
  122.           errors.h.
  123.  
  124. CopyWindowToDIB
  125. Syntax    HDIB CopyWindowToDIB(hWnd, fPrintArea)
  126.           
  127.           This function copies the specified part of the window
  128.           to a device-independent bitmap.
  129.           
  130.           Parameter      Type/Description
  131.           hWnd           HWND   Specifies the window.
  132.           
  133.           fPrintArea     WORD   Specifies the window area(s) to
  134.                                 copy into the device-
  135.                                 independent bitmap.
  136.           
  137. Return Value   The value returned identifies the device-
  138.           independent bitmap if the function is successful.
  139.           Otherwise, it is NULL.
  140.  
  141.  
  142. CopyScreenToDIB
  143. Syntax    HDIB CopyScreenToDIB(lpRect)
  144.           
  145.           This function copies the specified part of the screen
  146.           to a device-independent bitmap.
  147.           
  148.           Parameter      Type/Description
  149.           lpRect         LPRECT Pointer to a RECT data
  150.                                 structure that contains the
  151.                                 rectangle to be copied.
  152.           
  153. Return Value   The value returned identifies the device-
  154.           independent bitmap if the function is successful.
  155.           Otherwise, it is NULL.
  156.  
  157.  
  158. CopyWindowToBitmap
  159. Syntax    HBITMAP CopyWindowToBitmap(hWnd, fPrintArea)
  160.           
  161.           This function copies the specified part of  the
  162.           window to a device-dependent bitmap.
  163.           
  164.           Parameter      Type/Description
  165.           hWnd           HWND   Specifies the window.
  166.           
  167.           fPrintArea     WORD   Specifies the window area(s) to
  168.                                 copy into the device-
  169.                                 independent bitmap.
  170.           
  171. Return Value   The value returned identifies the device-
  172.           dependent bitmap if the function is successful.
  173.           Otherwise, it is NULL.
  174.  
  175.  
  176. CopyScreenToBitmap
  177. Syntax    HBITMAP CopyScreenToBitmap(lpRect)
  178.           
  179.           This function copies the specified part of the screen
  180.           to a device-dependent bitmap.
  181.           
  182.           Parameter      Type/Description
  183.           lpRect         LPRECT Pointer to a RECT data
  184.                                 structure that contains the
  185.                                 rectangle to be copied.
  186.           
  187. Return Value   The value returned identifies the deice-
  188.           dependent bitmap if the function is successful.
  189.           Otherwise, it is NULL.
  190.  
  191.  
  192. PrintDIB
  193. Syntax    WORD PrintDIB(hDib, fPrintOpt, wXScale, wYScale,
  194.                     szJobName)
  195.  
  196.           This function prints the specified DIB.
  197.  
  198.           Parameter      Type/Description
  199.           hDib           HDIB   Specifies the handle to a DIB
  200.                                 which is to be printed
  201.           
  202.           fPrintOpt      WORD   Specifies the printing option.
  203.           
  204.           wXScale        WORD   Specifies the x-axis scaling
  205.                                 factor for the printed window.
  206.                                 The x and y scaling factors
  207.                                 are only used if the PW_SCALE
  208.                                 option is selected for the
  209.                                 fPrintOpt parameter.
  210.           
  211.           wYScale        WORD   Specifies the y-axis scaling
  212.                                 factor.
  213.           
  214.           szJobName      LPSTR  Specifies the name of the print
  215.                                 job.  This string is used in
  216.                                 the job name sent to the print
  217.                                 spooler, as well as in the
  218.                                 print dialog box.
  219.  
  220. Return Value   0 if successful, or one of:  ERR_INVALIDHANDLE,
  221.           ERR_LOCK, ERR_SETABORTPROC, ERR_STARTDOC,
  222.           ERR_NEWFRAME, ERR_ENDDOC, ERR_GETDC,
  223.           ERR_STRETCHDIBITS.  These constants are defined in
  224.           errors.h.
  225.  
  226. SaveDIB
  227. Syntax    WORD SaveDIB(hDib, lpFileName)
  228.  
  229.           This function saves the specified DIB to a disk file
  230.           in Windows 3.0 DIB format.  Although the convention
  231.           for naming DIB files is to use a .BMP extension, the
  232.           entire file name must be specified.
  233.  
  234.           Parameter      Type/Description
  235.           hDib           HDIB   Specifies the handle to a DIB
  236.                                 which is to be saved.
  237.  
  238.           lpFileName     LPSTR  Specifies the complete path
  239.                                 name of the DOS filename under
  240.                                 which this DIB is to be saved.
  241.  
  242. Return Value   The value returned is zero for success or an
  243.           error code of one of the following:
  244.           ERR_INVALIDHANDLE, ERR_OPEN, or ERR_LOCK.
  245.  
  246. LoadDIB
  247. Syntax    HDIB LoadDIB(lpFileName)
  248.           
  249.           This function loads a DIB from the specified file,
  250.           allocates memory for the DIB, and returns a handle to
  251.           the DIB.
  252.           
  253.           Parameter      Type/Description
  254.           lpFileName     LPSTR  Specifies the complete path
  255.                                 name of the DOS filename of
  256.                                 the DIB to load.  This
  257.                                 function will load files with
  258.                                 any extension, but the
  259.                                 convention is to name DIB
  260.                                 files with a .BMP etension.
  261.           
  262. Return Value   The value returned identifies the deice-
  263.           dependent bitmap if the function is successful.
  264.           Otherwise, it is NULL.
  265.  
  266. DestroyDIB
  267. Syntax    WORD DestroyDIB(hDib)
  268.           
  269.           This function destroys the specified DIB, deleting
  270.           any memory associated with the DIB.  The handle to
  271.           the DIB is invalid after calling this function.
  272.           
  273.           Parameter      Type/Description
  274.           hDib           HDIB   Specifies the handle to the DIB
  275.                                 to destroy.
  276.           
  277. Return Value   The value returned is zero for success.
  278.  
  279.